'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH MAGIC 5 "Feb 6, 2004"
.SH NAME
magic \- file command's magic number file
.SH SYNOPSIS
.LP
.nf
\fB/etc/magic\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBfile\fR(1) command identifies the type of a file using, among other
tests, a test for whether the file begins with a certain \fImagic number\fR.
The \fB/etc/magic\fR file, or a file specified as an option-argument to the
\fB-m\fR or \fB-M\fR options of \fBfile\fR(1), specifies what magic numbers are
to be tested for, what message to print if a particular magic number is found,
and additional information to extract from the file.
.sp
.LP
Each line of the file specifies a position-sensitive test to perform. A test
compares the data starting at a particular offset in the file with a 1-byte,
2-byte, 4-byte, or 8-byte numeric value or string. If the test succeeds, a
message is printed. The line consists of the following fields (separated by
tabs): \fIoffset\fR \fItype\fR \fIvalue\fR \fImessage\fR
.sp
.ne 2
.na
\fB\fIoffset\fR\fR
.ad
.RS 11n
A number specifying the offset, in bytes, into the file of the data which is to
be tested.
.RE

.sp
.ne 2
.na
\fB\fItype\fR\fR
.ad
.RS 11n
The type of the data to be tested. The possible values are:
.sp
.ne 2
.na
\fB\fBbyte, d1, dC\fR\fR
.ad
.RS 24n
A one-byte signed value.
.RE

.sp
.ne 2
.na
\fB\fBshort, d2, dS\fR\fR
.ad
.RS 24n
A 2-byte signed value.
.RE

.sp
.ne 2
.na
\fB\fBlong, d4, dI, dL, d\fR\fR
.ad
.RS 24n
A 4-byte signed value.
.RE

.sp
.ne 2
.na
\fB\fBllong, d8\fR\fR
.ad
.RS 24n
An 8-byte signed value
.RE

.sp
.ne 2
.na
\fB\fBubyte, u1, uC\fR\fR
.ad
.RS 24n
A one-byte unsigned value.
.RE

.sp
.ne 2
.na
\fB\fBushort, u2, uS\fR\fR
.ad
.RS 24n
A 2-byte unsigned value.
.RE

.sp
.ne 2
.na
\fB\fBulong, u4, uI, uL, u\fR\fR
.ad
.RS 24n
A 4-byte unsigned value.
.RE

.sp
.ne 2
.na
\fB\fBullong, u8\fR\fR
.ad
.RS 24n
An 8-byte unsigned value.
.RE

.sp
.ne 2
.na
\fB\fBstring, s\fR\fR
.ad
.RS 24n
A string of bytes.
.RE

All type specifiers, except for \fBstring\fR and \fBs\fR, may be followed by a
mask specifier of the form \fB&\fR\fInumber\fR. If a mask specifier is given,
the value is AND'ed with the \fInumber\fR before any comparisons are done. The
\fInumber\fR is specified in C form. For instance, \fB13\fR is decimal,
\fB013\fR is octal, and \fB0x13\fR is hexadecimal.
.RE

.sp
.ne 2
.na
\fB\fIvalue\fR\fR
.ad
.RS 11n
The value to be compared with the value from the file. If the type is numeric,
this value is specified in \fBC\fR form. If it is a string, it is specified as
a \fBC\fR string with the usual escapes permitted (for instance, \en for
NEWLINE).
.sp
\fINumeric values\fR may be preceded by a character indicating the operation to
be performed, as follows:
.sp
.ne 2
.na
\fB\fB=\fR\fR
.ad
.RS 5n
The value from the file must equal the specified value.
.RE

.sp
.ne 2
.na
\fB\fB<\fR\fR
.ad
.RS 5n
The value from the file must be less than the specified value.
.RE

.sp
.ne 2
.na
\fB\fB>\fR\fR
.ad
.RS 5n
The value from the file must be greater than the specified value.
.RE

.sp
.ne 2
.na
\fB\fB&\fR\fR
.ad
.RS 5n
All the bits in the specified value must be set in the value from the file.
.RE

.sp
.ne 2
.na
\fB\fB^\fR\fR
.ad
.RS 5n
At least one of the bits in the specified value must not be set in the value
from the file.
.RE

.sp
.ne 2
.na
\fB\fBx\fR\fR
.ad
.RS 5n
Any value will match.
.RE

If the character is omitted, it is assumed to be "\fB=\fR".
.sp
For comparison of numeric values, the sign and size of both the value in the
file and the value from the \fIvalue\fR field of the magic entry will match
that of the corresponding \fItype\fR field. If there is a non-zero mask
(\fB&\fR) in the \fItype\fR field, the comparison will be unsigned.
.sp
For string values, the byte string from the file must match the specified byte
string. The byte string from the file which is matched is the same length as
the specified byte string. If the value is a string, it can contain the
following sequences:
.sp
.ne 2
.na
\fB\e\fIcharacter\fR\fR
.ad
.RS 15n
The backslash-escape sequences \fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR,
\fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR\&.
.RE

.sp
.ne 2
.na
\fB\e\fIoctal\fR\fR
.ad
.RS 15n
Octal sequences that can be used to represent characters with specific coded
values. An octal sequence consists of a backslash followed by the longest
sequence of one, two, or three octal-digit characters (01234567).
.RE

.RE

.sp
.ne 2
.na
\fB\fImessage\fR\fR
.ad
.RS 11n
The message to be printed if the comparison succeeds. If the string contains a
\fBprintf\fR(3C) format specification, the value from the file (with any
specified masking performed) is printed using the message as the format string.
.RE

.sp
.LP
Some file formats contain additional information which is to be printed along
with the file type. A line which begins with the character "\fB>\fR" indicates
additional tests and messages to be printed. If the test on the line preceding
the first line with a "\fB>\fR" succeeds, the tests specified in all the
subsequent lines beginning with "\fB>\fR" are performed, and the messages are
printed if the tests succeed. The next line which does not begin with a
"\fB>\fR" terminates this.
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/magic\fR\fR
.ad
.RS 14n

.RE

.SH SEE ALSO
.sp
.LP
.BR file (1),
.BR file (1B),
.BR printf (3C)
.SH NOTES
.sp
.LP
In Solaris 9 and prior releases, the file utility may have performed unsigned
comparisons for types \fBbyte\fR, \fBshort\fR, and \fBlong\fR. Old user-defined
magic files, which were specified with the \fB-m\fR option, will need
modification of \fBbyte\fR, \fBshort\fR, and \fBlong\fR entries to their
corresponding unsigned types (\fBubyte\fR, \fBushort\fR, or \fBulong\fR) for
those entries for which all of the following are true:
.RS +4
.TP
.ie t \(bu
.el o
The entry uses the "\fB<\fR" or the "\fB>\fR" operator.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBtype\fR field does not contain a non-zero mask.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The intention of the entry is to test unsigned values.
.RE
.sp
.LP
For example, if the following entry is expected to match any non-zero, one-byte
value from the file, including values for which the sign bit is on:
.sp
.in +2
.nf
#offset type    value   message
0       byte    >0      this matches any non-zero value
.fi
.in -2
.sp

.sp
.LP
then that entry should be changed to:
.sp
.in +2
.nf
0       ubyte    >0     this matches any non-zero value
.fi
.in -2
.sp

.sp
.LP
In Solaris 7 through Solaris 9, when applying tests for magic file entries
whose \fBtype\fR field is the numeric type "short" or "long", the file utility
in the x86 environment would switch the byte order of the numeric values read.
Starting in Solaris 10, the byte order will not be switched on x86. A test for
a numeric value whose byte order is identical in both little- and big-endian
architectures may require two magic file entries, to ensure that the test
correctly identifies files in both environments. For example, a magic file
entry that will match on a big-endian system may look like this:
.sp
.in +2
.nf
0       long      0xf00000ff      extended accounting file
.fi
.in -2
.sp

.sp
.LP
Its corresponding magic file entry that will match the same value on a
little-endian system would look like this:
.sp
.in +2
.nf
0       long      0xff0000f0      extended accounting file
.fi
.in -2
.sp

.SH BUGS
.sp
.LP
There should be more than one level of subtests, with the level indicated by
the number of `\fB>\fR' at the beginning of the line.
